<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8"/>
        <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"/>
        <title>AJ Security 框架-Google Recaptcha</title>
        <meta name="description" content="实用的 Java Web 安全库。Google Recaptcha"/>
        <meta name="keywords" content="security, xss, csrf, captcha, Google Recaptcha"/>
        <meta name="viewport" content="width=device-width, initial-scale=1"/>
        <link rel="stylesheet" href="https://framework.ajaxjs.com/static/font/font.css" />
        <link rel="stylesheet" href="/asset/main.css"/>
        <link rel="icon" type="image/x-icon" href="https://framework.ajaxjs.com/aj-logo/logo.ico"/>
        <script src="https://framework.ajaxjs.com/static/aj-docs/common.js"></script>
        <script>
            // 获取用户的默认语言
            var userLang = navigator.language || navigator.userLanguage;

            // 检查是否为中文环境（包括简体和繁体）
            if (userLang.startsWith('zh') && location.pathname.indexOf('cn') == -1) {
                 confirm('欢迎！您可以改为访问中文内容。是否继续？') && location.assign('/cn');  // 如果是中文，则弹出提示
            }

            var _hmt = _hmt || [];
            (function() {
              var hm = document.createElement("script");
              hm.src = "https://hm.baidu.com/hm.js?950ba5ba1f1fe4906c3b4cf836080f03";
              var s = document.getElementsByTagName("script")[0];
              s.parentNode.insertBefore(hm, s);
            })();
        </script>
    </head>
    <body>
        <nav>
            <div>
                <div class="links">
                    <a href="/">🏠 首页</a>
                    | ⚙️ 源码:
                    <a target="_blank" href="https://github.com/lightweight-component/aj-security">Github</a>/<a target="_blank" href="https://gitcode.com/lightweight-component/aj-security">Gitcode</a>
                    |
                    <a href="/">英文版本</a>
                </div>
                <h1><img src="https://framework.ajaxjs.com/aj-logo/logo.png" style="vertical-align: middle;height: 45px;margin-bottom: 6px;" /> AJ Security</h1>
                <h3>用户手册</h3>
            </div>
        </nav>
        <div>
            <menu>
                <ul>
                    <li class="selected">
                        <a href="/cn">首页</a>
                    </li>
                    <li>
                        <a href="/install-cn">安装与配置</a>
                    </li>
                </ul>
                <h3>HTTP Web 安全</h3>
                <ul>
                    <li>
                        <a href="/http/http-referer-cn">HTTP Referer 校验</a>
                    </li>
                    <li>
                       <a href="/http/timestamp-cn">时间戳加密 Token 校验</a>
                    </li>
                     <li>
                       <a href="/http/paramssign-cn">请求参数防篡改</a>
                    </li>
                    <li>
                       <a href="/http/ip-list-cn">IP 白名单/黑名单</a>
                    </li>
                     <li>
                       <a href="/http/nonrepeatsubmit-cn">防止重复提交数据</a>
                    </li>
                </ul>
                <h3>一般性 Web 校验</h3>
                <ul>
                      <li>
                           <a href="/classic/xss-cn">防止 XSS 跨站攻击</a>
                      </li>
                      <li>
                           <a href="/classic/crlf-cn">防止 CRLF 攻击</a>
                      </li>
                </ul>

                <h3>验证码 Captcha 机制</h3>
                <ul>
                    <li><a href="/captcha/img-captcha-cn">图片验证码</a></li>
                    <li><a href="/captcha/google-cn">基于 Google 的验证码</a></li>
                    <li><a href="/captcha/cf-cn">基于 CloudFlare 的验证码</a></li>
                </ul>
                <h3>HTTP 标准认证</h3>
                <ul>
                    <li><a href="/auth/http-basic-auth-cn">HTTP Basic Auth 认证</a></li>
                    <li><a href="/auth/http-digest-auth-cn">HTTP Digest Auth 认证</a></li>
                </ul>
                <h3>API 接口功能</h3>
                <ul>
                    <li><a href="/api/limit-cn">限流限次数</a></li>
                </ul>
                <h3>其他实用功能</h3>
                <ul>
                    <li><a href="/misc/desensitize-cn">实体字段脱敏</a></li>
                    <li><a href="/misc/encryption-api-cn">API 接口加解密</a></li>
                    <li><a href="/misc/trace-id-cn">链路跟踪记录</a></li>
                </ul>
            </menu>
            <article>
                <h1>Google Recaptcha</h1>
<p>我们封装了 Google Recaptcha 验证，方便使用。reCAPTCHA v3 很牛逼，取消了用户互动交互，做到无感知验证。</p>
<h2>准备</h2>
<p>要有谷歌账户，去注册 <a href="https://www.google.com/recaptcha/admin">https://www.google.com/recaptcha/admin</a>。我们使用 reCAPTCHA v3</p>
<p><img src="/captcha/413153c9f85df5e54d02b1401f3da4de.png" alt=""></p>
<p>填入你的域名，技巧：
1、可多个域名存放在一个网站下（其实实际是不同网站也没关系）</p>
<p>2、添加 <code>localhost</code> 便于本地开发测试</p>
<p>最后获取 appId 和密钥。</p>
<p><img src="/captcha/1.jpg" alt=""></p>
<h1>使用</h1>
<p>我们使用自定义用法。</p>
<h2>引入脚本</h2>
<pre><code class="language-html">&lt;!-- Google 防注册机验证 --&gt;
&lt;style&gt;.grecaptcha-badge{display: none;}&lt;/style&gt; 
&lt;script src=&quot;https://www.recaptcha.net/recaptcha/api.js?render=XXXX&quot;&gt;&lt;/script&gt;
</code></pre>
<p><code>render</code> 参数是你的客户 appId，注意不是密钥。另外一个样式是隐藏 Google 标签的，自然大多数客户不想看到。</p>
<p><img src="/captcha/164f43cd827274a704fa4002b62dc529.png" alt=""></p>
<h2>前端</h2>
<p>一般来说要写入操作的表单都要验证一下（写入的操作）。我们在表单之前获取 Token 并作为参数传到后端。下面是标准表单提交的例子。</p>
<pre><code class="language-html">&lt;script src=&quot;https://www.recaptcha.net/recaptcha/api.js?render=6LclfLMZAAAAAKC3YUTP4E3Ylc0PSvfXpneRePAH&quot;&gt;&lt;/script&gt;

&lt;form id=&quot;myForm&quot; action=&quot;http://localhost:8083/foo/captcha_google&quot; method=&quot;POST&quot;&gt;
    &lt;input type=&quot;text&quot; name=&quot;name&quot; /&gt;
    &lt;br /&gt;
    &lt;input type=&quot;text&quot; name=&quot;age&quot; /&gt;
    &lt;br /&gt;
    &lt;input type=&quot;hidden&quot; name=&quot;grecaptchaToken&quot; id=&quot;recaptchaToken&quot; /&gt;
    &lt;button type=&quot;submit&quot;&gt;Submit&lt;/button&gt;
    &lt;p id=&quot;status&quot;&gt;&lt;/p&gt;
&lt;/form&gt;

&lt;script&gt;
    document.getElementById('myForm').addEventListener('submit', function (e) {
    debugger
      e.preventDefault(); // Prevent default form submission
    
      const form = e.target;
      const tokenInput = document.getElementById('recaptchaToken');
    
      grecaptcha.ready(function () {
        grecaptcha.execute('6LclfLMZAAAAAKC3YUTP4E3Ylc0PSvfnp8eRePAH', { action: 'submit' }).then(function (token) {
        debugger
          tokenInput.value = token; // Set token value in hidden input
          form.submit(); // Now submit the form
        });
      });
    });

&lt;/script&gt;
</code></pre>
<p>相应修改 appId 即可。</p>
<p>POST JSON Raw Body 的例子：</p>
<pre><code class="language-javascript">document.getElementById('myForm').addEventListener('submit', function (e) {
  e.preventDefault();

  const form = e.target;
  const status = document.getElementById('status');

  // Execute reCAPTCHA
  grecaptcha.ready(function () {
    grecaptcha.execute('6LclfLMZAAAAAKC3YUTP4Ylc0PSvfnpneRePAH', { action: 'submit' }).then(function (token) {
      // Add token to form data
      const formData = new FormData(form);
      formData.append('token', token);

      // Submit form via fetch
      fetch('/api/submit-form', {
        method: 'POST',
        body: JSON.stringify(Object.fromEntries(formData)),
        headers: {
          'Content-Type': 'application/json'
        }
      }).then(response =&gt; response.json()).then(data =&gt; {
        status.textContent = data.message || 'Success!';
        status.style.color = 'green';
        form.reset();
      }).catch(error =&gt; {
        status.textContent = 'An error occurred.';
        status.style.color = 'red';
        console.error('Error:', error);
      });
    });
  });
});

</code></pre>
<h2>服务端处理</h2>
<p>后端的原理就是把传入的 token 再请求 Google 校验是否合法。</p>
<h3>yaml 配置</h3>
<p>配置文件 <code>application.yml</code> 中添加如下内容：</p>
<pre><code class="language-yaml">security:
  captcha:
    google:
      enabled: true
      globalCheck: false # 全局检查
      accessSecret: 6LclfLMZAAAAAD6XUpBL0qHKYWijay7-lGpOf
</code></pre>
<h3>拦截校验</h3>
<p>在使用的接口上添加<code>@GoogleCaptchaCheck</code>注解：</p>
<pre><code class="language-java">@PostMapping(&quot;/captcha_google&quot;)
@GoogleCaptchaCheck
boolean google(@RequestParam(GoogleCaptcha.PARAM_NAME) String token, @ModelAttribute User user);
</code></pre>
<p>校验通过，结果如下:</p>
<p><img src="/captcha/d20ef7798177009e31b7125122736d5f.png" alt=""></p>

            </article>
        </div>
        <footer>
             AJ Security，开源框架 <a href="https://framework.ajaxjs.com" target="_blank">AJ-Framework</a> 的一部分。联系方式：
             frank@ajaxjs.com，<a href="https://blog.csdn.net/zhangxin09" target="_blank">作者博客</a>
             <br />
             <br />
             Copyright © 2025 Frank Cheung. All rights reserved.
         </footer>
    </body>
</html>